updateFlags called on every render — overwrites live flag updates

updateFlags is invoked unconditionally during the render phase, so it runs on every re-render of ClientPostHogProvider (e.g. page navigation, parent state change). Because updateFlags defaults to replace mode (no merge: true), it will clobber any real-time flag values that PostHog received from the network after the initial load, reverting the user's flags back to the stale bootstrap snapshot each time.

It also runs during SSR (since the typeof window guard was removed), where the posthog-js singleton may not be fully initialised, making the call a potential no-op or source of unexpected behaviour server-side.

The call should be protected so it only fires once on the client, for example by tracking whether it has already been applied:

// Track whether the bootstrap flags have been applied to avoid
// overwriting live flag updates on subsequent re-renders.
const bootstrapApplied = React.useRef(false)

if (!posthogJs.__loaded) {
    posthogJs.init(apiKey, mergedOptions)
}

if (bootstrap?.featureFlags && !bootstrapApplied.current) {
    posthogJs.updateFlags(bootstrap.featureFlags)
    bootstrapApplied.current = true
}

(A useEffect could also be used, but the existing pattern deliberately initialises during render for the reasons explained in the JSDoc.)

Rule Used: Add inline comments to clarify the purpose of sign... (source)

Learnt From
PostHog/posthog#32083

This is a comment left during a code review.
Path: packages/next/src/client/ClientPostHogProvider.tsx
Line: 50-53

Comment:
**`updateFlags` called on every render — overwrites live flag updates**

`updateFlags` is invoked unconditionally during the render phase, so it runs on **every re-render** of `ClientPostHogProvider` (e.g. page navigation, parent state change). Because `updateFlags` defaults to *replace* mode (no `merge: true`), it will clobber any real-time flag values that PostHog received from the network after the initial load, reverting the user's flags back to the stale bootstrap snapshot each time.

It also runs during SSR (since the `typeof window` guard was removed), where the posthog-js singleton may not be fully initialised, making the call a potential no-op or source of unexpected behaviour server-side.

The call should be protected so it only fires once on the client, for example by tracking whether it has already been applied:

```tsx
// Track whether the bootstrap flags have been applied to avoid
// overwriting live flag updates on subsequent re-renders.
const bootstrapApplied = React.useRef(false)

if (!posthogJs.__loaded) {
    posthogJs.init(apiKey, mergedOptions)
}

if (bootstrap?.featureFlags && !bootstrapApplied.current) {
    posthogJs.updateFlags(bootstrap.featureFlags)
    bootstrapApplied.current = true
}
```

(A `useEffect` could also be used, but the existing pattern deliberately initialises during render for the reasons explained in the JSDoc.)

**Rule Used:** Add inline comments to clarify the purpose of sign... ([source](https://app.greptile.com/review/custom-context?memory=4d5b48c5-045d-4693-9cd9-4081bb19508b))

**Learnt From**
[PostHog/posthog#32083](https://github.com/PostHog/posthog/pull/32083)

How can I resolve this? If you propose a fix, please make it concise.

I don't think we need the useRef here, but we should only either init or updateFlags. if/else seems reasonable.

Looking at the code, I need to point out that using if/else doesn't solve the re-render problem that was raised:

With if/else structure:

if (!posthogJs.__loaded) {
    posthogJs.init(apiKey, mergedOptions)  // Run once
} else if (bootstrap?.featureFlags) {
    posthogJs.updateFlags(bootstrap.featureFlags)  // Run on EVERY subsequent render
}

What happens:

• Render 1: __loaded = false → calls init() → __loaded becomes true
• Render 2+: __loaded = true → skips init, executes else if → calls updateFlags() each time

The component could re-render for various reasons (parent state change, navigation, React StrictMode, etc.), and each re-render would call updateFlags() with the bootstrap snapshot, overwriting any live flags fetched from PostHog's servers.

Question: Are you thinking that:

1. mergedOptions already contains the bootstrap data, so init() handles it and we don't need updateFlags at all?
2. Or that this component won't re-render in practice, so the else if is effectively a one-time call?

If option 1, we should remove the updateFlags call entirely. If option 2, we should still guard against re-renders since they can happen unexpectedly.

Changeset bump type should be patch, not minor

This is a bug fix, which maps to a patch version bump in semver. A minor bump is reserved for new backwards-compatible features.

This is a comment left during a code review.
Path: .changeset/shy-jeans-rescue.md
Line: 2

Comment:
**Changeset bump type should be `patch`, not `minor`**

This is a bug fix, which maps to a `patch` version bump in semver. A `minor` bump is reserved for new backwards-compatible features.

```suggestion
'@posthog/next': patch
```

How can I resolve this? If you propose a fix, please make it concise.

Missing test: updateFlags called when already loaded

The two new tests only cover the case where __loaded = false (the beforeEach default). There is no test verifying that updateFlags is still called when __loaded = true — i.e. when posthog was initialised in a previous render and init() is skipped. This is the production steady-state after the first mount. Adding a test for it would document and guard the intended behaviour, ensuring the bootstrap flags are applied on subsequent renders even after init has already run.

This is a comment left during a code review.
Path: packages/next/tests/ClientPostHogProvider.test.tsx
Line: 127-149

Comment:
**Missing test: `updateFlags` called when already loaded**

The two new tests only cover the case where `__loaded = false` (the `beforeEach` default). There is no test verifying that `updateFlags` is still called when `__loaded = true` — i.e. when posthog was initialised in a previous render and `init()` is skipped. This is the production steady-state after the first mount. Adding a test for it would document and guard the intended behaviour, ensuring the bootstrap flags are applied on subsequent renders even after init has already run.

How can I resolve this? If you propose a fix, please make it concise.

Also consider payloads

A configurable option sounds great; personally, I think always rendering on the server is a sensible default, as the flicker can be a massive deal for user experience. Users may not notice a small increase in load time, but they'll definitely notice the flicker, and it could make the website owners seem like they're running a visibly buggy site. Though, off the top of my head, I'm not sure how bootstrapping only on first page load could be achieved, and whether this could reintroduce the flicker.

In response to the useEffect you mentioned, I've actually tried testing this and I think it might cause another issue; I get a NextJs error saying that it can't update one of my components at the same time as ClientPosthogProvider.

Thanks for the correction on the "else if" and the flag payloads.